home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1993…ch: Other People's Memory / ADC Developer CD (1993-03) (''Other People's Memory'')_iso / Dev.CD Mar 93.iso / Development Platforms / Apple II / Essentials / Technical.Notes / IIGS / TN.IIGS.053 < prev    next >
Encoding:
Text File  |  1992-07-15  |  14.5 KB  |  319 lines  |  [TEXT/GEOL]
  1. Apple II
  2. Technical Notes
  3. _____________________________________________________________________________
  4.                                                   Developer Technical Support
  5. Apple IIgs
  6. #53: Desk Accessories and Tools
  7.  
  8. Revised by: Dave "Out of Phase" Lyons                                May 1992
  9. Written by: Matt Deatherage, Jim Mensch, & Dave Lyons              March 1989
  10.  
  11. This Technical Note discusses compatibility issues that can arise between desk
  12. accessories and applications.  Where possible, it presents solutions.
  13.  
  14. CHANGES SINCE MARCH 1991:  Updated information about QuickDraw Auxiliary and
  15. StartUpTools for System 6.0.
  16. _____________________________________________________________________________
  17.  
  18.  
  19. This Note presents guidelines to help applications and desk accessories work
  20. together smoothly.
  21.  
  22. TOOL SETS
  23.  
  24. The greatest conflict between applications and desk accessories, especially
  25. NDAs, is the use of system tool sets.  The Apple IIgs Toolbox Reference,
  26. Volume 1, defines the minimum collection of tools sets available to an NDA.
  27. The Desk Manager requires that an application start the following tool sets
  28. before calling DeskStartUp:
  29.  
  30.      Tool Locator (#1)
  31.      Memory Manager (#2)
  32.      Miscellaneous Tools (#3)
  33.      QuickDraw II (#4)
  34.      Event Manager (#6)
  35.      Window Manager (#14)
  36.      Menu Manager (#15)
  37.      Control Manager (#16)
  38.      LineEdit (#20)
  39.      Dialog Manager (#21)
  40.      Scrap Manager (#22)
  41.  
  42. NDAs may assume that these tools are all present and running, so they do not
  43. need to check for their presence.  NDAs can also use the following tool sets
  44. without special consideration for starting them up:  Desk Manager, Scheduler,
  45. Apple Desktop Bus, and Integer Math.
  46.  
  47. In addition to the tool sets applications must start to support NDAs, Apple
  48. recommends that applications start the following tools:
  49.  
  50.      QuickDraw Auxiliary (#18)     (see discussion under QuickDraw Auxiliary)
  51.      Font Manager (#27)
  52.  
  53. These two additional tools are so widely used by desk accessories that they
  54. should be present.  NDAs may not assume their presence, but it is reasonable
  55. to write an NDA that checks for them, with the assumption that they usually
  56. turn out to be available.
  57.  
  58.  
  59. NDA GUIDELINES
  60.  
  61. WHICH TOOL SETS CAN AN NDA USE?
  62.  
  63.    o   In general, NDAs can use the tool sets which have already been started
  64.        up by the host application, even tools that are not guaranteed to be
  65.        started up.  Using other tool sets is trickier (see below).
  66.  
  67.  
  68.    o   In general, NDAs should not start up tools that are already started
  69.        up.  (The Resource Manager is an exception.)
  70.  
  71.    o   The Resource Manager must be started separately by each client.  See
  72.        Apple IIgs Technical Note #71 for detailed information on using the
  73.        Resource Manager from an NDA.
  74.  
  75.    o   Sound tools are an exception to the rule of freely using a tool which
  76.        is already started. See the section "Sound Tools" sections later in
  77.        this note.
  78.  
  79.    o   Some tool sets are easily started up each time they are needed, if
  80.        they are not already present.
  81.  
  82.  
  83.        Standard File is an excellent example.  If an NDA needs to use
  84.        Standard File, it should check to see if the tool is already running.
  85.        If it is not running, the NDA must use LoadOneTool to load it, then
  86.        it must allocate a page of direct-page space and start the tool
  87.        before using it.  When finished with the tool, the NDA must shut it
  88.        down, deallocate the direct-page space, and unload it with
  89.        UnloadOneTool.  (A tool is already running if its xxxStatus function
  90.        returns TRUE and does not return an error.)
  91.  
  92.  
  93.        The important thing here is that the NDA shuts down Standard File
  94.        imediately after using it, if it was not already started.  This does
  95.        not cause conflicts with the host application or with other NDAs.
  96.  
  97.        Note that by pre-initializing the result space of an xxxStatus call to
  98.        zero, you can avoid caring whether the tool is present but not started
  99.        or simply not present.
  100.  
  101.             pea $0000
  102.             _SFStatus
  103.             pla                   ;A is nonzero if Standard File is started
  104.  
  105.        From a high-level language, you may not be able to pre-initialize the
  106.        result space.  Instead, you need something like the C statement:
  107.  
  108.             StdFileActive = ( SFStatus() && !_toolErr);
  109.  
  110.        or the Pascal statement:
  111.  
  112.             StdFileActive := (SFStatus<>0) AND (ToolErrorNum=0);
  113.  
  114.    o   It is impractical or impossible to start up certain tool sets each
  115.        time they are needed.  These include the Font Manager, Scrap Manager,
  116.        and Text Edit.
  117.  
  118.        If an NDA needs to start up a tool and keep it started while letting
  119.        the application continue to run, things get interesting.  (There is a
  120.        risk that the host application will later try to start up the tool set
  121.        itself and not be able to deal with the tool already being started.)
  122.  
  123.        In practice, the safest thing you can do for a tool you need to leave
  124.        running is:
  125.  
  126.        --When your NDA is opened, check the tool set's status.  If it is not
  127.        available, use LoadOneTool, allocate any needed direct-page space,
  128.        start up the tool set, and set a flag indicating that your NDA started
  129.        the tool set.
  130.  
  131.        --When your NDA's Init routine is called at DeskShutDown time
  132.        (Accumulator equal to zero), check the flag set above.  If your NDA
  133.        started a tool set, shut it down, dispose of any direct-page space you
  134.        allocated for it, and call UnloadOneTool.
  135.  
  136.        (Keep in mind that your NDA can be opened and closed many times before
  137.        DeskShutDown is called when the application finally quits.  If you
  138.        have started a tool and set a flag on an open, be sure not to disturb
  139.        the flag on a future open, when the tool is already available because
  140.        you started it!  You still need to shut it down at DeskShutDown time.)
  141.  
  142.        --Do not shut down tool sets when your NDA is closed.  To see why,
  143.        consider what would happen if two NDAs just like yours were used at
  144.        the same time.  If the NDAs were closed in any other than the exact
  145.        opposite order they were opened, some NDAs would have tool sets shut
  146.        down from underneath them.
  147.  
  148. STARTUPTOOLS
  149.  
  150.    o   StartUpTools in System Software 5.0.4 and earlier is designed to be
  151.        called only by an application, not a desk accessory.  Unexpected
  152.        things happen if your NDA calls StartUpTools (for example, you may get
  153.        a second copy of the application's resource fork open in your NDA's
  154.        private resource search path; this wastes RAM and can interfere with
  155.        an application's attempt to write to its own resource fork).
  156.  
  157.    o   See the System 6.0 Toolbox documentation for information on using
  158.        StartUpTools from an NDA.  There are new flag bits you need to know
  159.        about.
  160.  
  161. TLSTARTUP AND TLSHUTDOWN
  162.  
  163.    o   Do not call TLStartUp or TLShutDown from a desk accessory.
  164.  
  165.    o   You may call MMStartUp at any time to get your desk accessory's own
  166.        memory ID.  This does not allocate a new ID; it just tells you what ID
  167.        you already have (it returns the memory ID of the block the MMStartUp
  168.        call is made from).
  169.  
  170. USER TOOL SETS BELONG TO THE APPLICATION
  171.  
  172.    o   A desk accessory must not install user tool sets, because there is no
  173.        arbitration of user tool set numbers.  User tool sets are the sole
  174.        property of the current application.
  175.  
  176.        A desk accessory should not call user tool sets even if it determines
  177.        that the host application has installed a certain tool set, because
  178.        that limits future system software options.  For example, consider a
  179.        hypothetical multiple-application environment.  If DAs call user tool
  180.        sets and the system automatically switches between separate
  181.        collections of user tool sets, there would be no way for the system to
  182.        know which set to switch in before giving control to a desk accessory. 
  183. BANK ZERO MEMORY AND ERROR $0201
  184.  
  185.    o   If you get error $0201 (unable to allocate memory block) while trying
  186.        to launch a ProDOS 8 application, it is probably because your NDA
  187.        allocated some memory in bank 0 or bank 1 and failed to dispose of it
  188.        at DeskShutDown time (when the NDA's Init routine is called with the
  189.        accumulator equal to zero).  GS/OS needs to allocate all of this
  190.        memory for ProDOS 8 to use.
  191.  
  192. QUICKDRAW AUXILIARY
  193.  
  194.    o   In System 6.0 and later, QuickDraw Auxiliary is always available to an
  195.        NDA, because the Window Manager automatically loads and starts
  196.        QuickDraw Auxiliary (because it's needed for AlertWindow, for
  197.        example).  To prevent problems, duplicate QDAuxStartUp and
  198.        QDAuxShutDown calls are tolerated, and QDShutDown automatically calls
  199.        QDAuxShutDown.
  200.  
  201.    o   Before System 6.0, starting QuickDraw Auxiliary when the application
  202.        has not started it can be a problem.  An application that correctly
  203.        implements switching between 320 and 640 mode calls QDShutDown and
  204.        QDStartUp.  QuickDraw Auxiliary depends heavily on QuickDraw, and
  205.        restarting QuickDraw while QuickDraw Auxiliary is active will fry
  206.        big-time.
  207.  
  208.  
  209. SOUND TOOLS
  210.  
  211.    o   A desk accessory cannot use any of the sound tools if they are already
  212.        started.  This is contrary to the rule for other tool sets, but it is
  213.        required because there is no memory management of the sound RAM (or
  214.        "DOC RAM").  If the Sound Tools (#8) are started, the application has
  215.        exclusive control of the 64K DOC RAM used to play sounds.  Anything
  216.        your desk accessory might put there could overwrite information the
  217.        application needs.
  218.  
  219.        Saving and restoring DOC RAM around desk accessory usage is not
  220.        sufficient.  Many of the sound functions are interrupt driven,
  221.        altering the contents of DOC RAM only during sound interrupts, so your
  222.        desk accessory might attempt to replace parts of DOC RAM which are
  223.        being played.  Since there is no memory management of DOC RAM, desk
  224.        accessories must avoid the sound functions of the IIgs if the
  225.        application is already using them.
  226.  
  227.  
  228. APPLICATION GUIDELINES
  229.  
  230. For best compatibility with NDAs, applications should follow the following
  231. guidelines.
  232.  
  233.    o   Be careful about when your application starts and shuts down tools.  A
  234.        highly compatible approach is to start tools at the beginning of your
  235.        application and leave them started.  For certain tools, like Standard
  236.        File, it is reasonable to load and start the tool set each time it's
  237.        needed (you may want to check whether it's already started, in case
  238.        some impolite NDA started Standard File and left it started).
  239.  
  240.        Note that UnloadOneTool followed later by LoadOneTool does not
  241.        necessarily cause disk access or ask the user to insert the boot disk.
  242.        UnloadOneTool calls UserShutDown to put the tool set into "zombie"
  243.        state, where it can be restarted from memory if none of its segments
  244.        have been purged.  Unloading tools while they aren't in use is a Good
  245.        Thing--if the user has plenty of RAM, there's no noticeable
  246.        performance hit, but if RAM space is tight then doing extra disk
  247.        access still is preferable to actually running out of memory.
  248.  
  249.        For maximum compatibility, an application should not shut down any
  250.        tools which were ever active when it called SystemTask or TaskMaster
  251.        (until quitting time, of course, when it shuts down everything,
  252.        starting with the Desk Manager).  The application can start more
  253.        tools, but it should not shut down those which are already active.
  254.  
  255.        If your application is going to start a tool and not keep it started,
  256.        use it and then shut it down immediately, without allowing desk
  257.        accessories to be opened during that time.
  258.  
  259.    o   Don't just start the Scrap Manager--use it!  Many desk accessories
  260.        support cutting and pasting to exchange text and pictures with your
  261.        application, but they can do it only if you use the Scrap Manager.  If
  262.        you have a need for your own private scrap internally, you should
  263.        still also use the Scrap Manager to exchange text and pictures with
  264.        other applications and DAs.
  265.  
  266.    o   Provide an Edit menu, and when an NDA window comes to the front enable
  267.        the menu and the Undo, Cut, Copy, Paste, and Clear items.
  268.  
  269.    o   Applications should never make a Close call with reference number zero
  270.        at file level zero.  (If you need to use Close with reference number
  271.        zero, use GetLevel and SetLevel to avoid closing files you did not
  272.        open.)
  273.  
  274.        DAs written recently can open their files at an internal file level,
  275.        as documented in GS/OS Technical Note #13, but applications still need
  276.        to avoid closing all files at level zero for compatibility with older
  277.        desk accessories.
  278.  
  279.    o   An application with some memory to spare can save NDAs time by
  280.        providing them the additional tools which they are most likely to use.
  281.  
  282.        The most common tools which desk accessories require besides those
  283.        available in the standard Desk Manager set are QuickDraw Auxiliary
  284.        (#18), the Print Manager (#19), Standard File (#23), the Font Manager
  285.        (#27), and the List Manager (#28).
  286.  
  287.    o   When you call TaskMaster or GetNextEvent, or EventAvail, be sure bit
  288.        10 is turned on in the event mask, to enable "desk accessory" events.
  289.        If you turn this bit off, users will not be able to get to the Classic
  290.        Desk Accessory menu by pressing Apple-Ctrl-ESC.
  291.  
  292. CDA GUIDELINES
  293.  
  294.    o   CDAs are nearly always modal, but by using the HeartBeat interrupt
  295.        queue or other mechanisms, they can get control when the user is no
  296.        longer "in" the CDA.  The list of guaranteed tools for NDAs does not
  297.        apply to CDAs, and CDAs must be prepared to deal with the ProDOS 8
  298.        environment as well as GS/OS.
  299.  
  300.    o   Under ProDOS 8, a CDA will not be able to allocate any bank 0 space
  301.        through the Memory Manager; it can only use page 0 and page 1 safely
  302.        (the stack is in page 1).
  303.  
  304.    o   Do not call TLStartUp or TLShutDown from a desk accessory.
  305.  
  306.    o   You may call MMStartUp at any time to get your DA's own memory ID.
  307.        This does not allocate a new ID; it just tells you what ID you already
  308.        have (it returns the memory ID of the block the MMStartUp call is made
  309.        from).
  310.  
  311.  
  312. Further Reference:
  313. _____________________________________________________________________________
  314.  
  315.    o   Apple IIgs Toolbox Reference
  316.    o   Programmer's Introduction to the Apple IIgs
  317.    o   Apple IIgs Technical Note #71, Desk Accessory Tips and Techniques
  318.    o   Apple IIgs Technical Note #83, Resource Manager Stuff
  319.